Documentation for class database

Inherits from 	complex_object 

Properties declared in database 

Class Methods declared in database 
	new 

Methods declared in database 
	action 
		add_current_record 
		close_manager 
		display_current_record 
		goto_first_record 
		goto_first_record_and_display 
		goto_last_record 
		goto_last_record_and_display 
		goto_next_record 
		goto_next_record_and_display 
		goto_previous_record 
		goto_previous_record_and_display 
		load_and_add_current_record 
		load_and_update_current_record 
		load_current_record 
		open_manager 
		remove_current_record 
		update_current_record 
		update_manager 
	any 
		add_current_record 
		average_field(field) 
		clear_controls 
		close_manager 
		current_record_number 
		display_current_record 
		does_sort_decreasing(field) 
		empty 
		export(fields, file, field_delimiter, record_delimiter) 
		fields 
		find_number(fields, number, find_option, search_backwards, test_only_current) 
		get_field(field) 
		goto_first_record 
		goto_first_record_and_display 
		goto_last_record 
		goto_last_record_and_display 
		goto_next_record 
		goto_next_record_and_display 
		goto_previous_record 
		goto_previous_record_and_display 
		has_backing_store 
		import(file, field_delimiter, record_delimiter) 
		input_control_for(field) 
		load_and_add_current_record 
		load_and_update_current_record 
		load_current_record 
		max_field(field) 
		min_field(field) 
		open_manager 
		output_control_for(field) 
		remove_current_record 
		search(fields, pattern, search_type, ignore_case, allow_regular_expr, search_backwards, test_only_current) 
		set_field(field, value) 
		set_input_control_for(field, object) 
		set_output_control_for(field, object) 
		size 
		sort(fields) 
		sort_decreasing(fields, boolean) 
		sum_field(field) 
		update_current_record 
		update_manager 

Class 
#begin_class
database 
The class database is a subclass of the class complex_object. 
Database objects are designed to store large amounts of data. A database may be sorted and searched and it can import/export data from/to text files.
A database is an ordered collection of records. A record is a number of values stored in fields:

           Field 1  Field 2
Record 1:   Value   Value
Record 2:   Value   Value
Record 3:   Value   Value
  .       .     .
  .       .     .
Record n:   Value   Value

Every field has a type that determines the type of data that can be stored in the field. Valid types are string, integer, float, boolean, color and text.

There is always a current record in the database. Usually the values of the fields in the current record are shown in text-fields in your program. From the current record you can reach the next record and the previous record. You can also go to the first record and the last record in the database. 
You cannot refer to a record directly by index in a database.

The fields in the database may be connected to controller objects in your program. Each field may have one output controller and one input controller connected to itself. The output controller continuously shows the value in the field of the current record. The input controller may change the value in the field of the current record.

The Database Manager is a window that may be opened by the database. The Database Manager is a tool to help you test your database. Almost all the things you can do by sending messages to the database can also be done in the Database Manager window.

Note: Databases can only be created in edit-mode. You create databases in the program appearance inspector, and you create the fields of the database with the database appearance inspector. 
#end_class

Properties 

Methods 

#begin_method
add_current_record 
Adds the current record to the database. This message should be sent to the database after one or more set_field(field, value) messages have been used to set the values of the fields in the current record.
Returns self.
Also see update_current_record.
#end_method

#begin_method
average_field(field) 
Returns the average of all the values of field in the database. The field must be of the type integer or float. Otherwise the method returns 0.
#end_method

#begin_method
clear_controls 
Clears all the controls that are connected to the fields of the database. The controls will be emptied or set to 0 depending on the type of the field.
Returns self.
#end_method

#begin_method
close_manager 
Closes the Database Manager window.
Returns self.
Also see open_manager.
#end_method

#begin_method
current_record_number 
Returns the index of the current record.
#end_method

#begin_method
display_current_record 
Sets the values of the input and output controllers that are connected to the fields of the database. The values of the current record will be used.
Returns self.
Note: The values of the controllers will not be set by the set_value method.
#end_method

#begin_method
does_sort_decreasing(field) 
Returns true if the field sorts in decreasing order. Otherwise the method returns false.
#end_method

#begin_method
empty 
Removes all the records of the database.
Returns self.
Note: This operation may destroy large amounts of data.
#end_method

#begin_method
export(fields, file, field_delimiter, record_delimiter) 
Exports the contents of the database to a text-file with the name file. 
If file is not a complete filename the file will be placed in the home directory. 
fields are a collection of the name of the fields you want to export.
field_delimiter is the character that will delimit fields in the text-file.
record_delimiter is the character that will delimit records in the text-file.
Ex:
Assume that the database {database my_base} has three fields: name, phone and birthdate.

{database my_base}:export([#name #phone], "myfile.txt", \tab, \nl)
will create a text-file named "myfile.txt" of two of the fields that will look something like:
Steve	234 5656
Mike	123 3243
Lucy	873 1293

{database my_base}:export({database my_base}:fields,  "myfile.txt", \,, \nl)
will create a text-file named "myfile.txt" of all the fields that will look something like:
Steve,234 5656,2 Oct
Mike,123 3243,8 Nov
Lucy,873 1293,23 Jan
#end_method

#begin_method
fields 
Returns a collection of the names of the fields of the database. 
Ex:
Assume that the database {database my_base} has three fields: name, phone and birthdate.
{database my_base}:fields
returns [#name #phone #birthdate]
#end_method

#begin_method
find_number(fields, number, find_option, search_backwards, test_only_current) 
Searches the database for a number. Only the fields specified by the collection fields are searched.
If a number is found, the method returns the name of the field that included the number. The current record will be set to the record where the number was found. If there is no number in the database that matches the method returns false.
The argument find_option specifies the find option:
#equal finds numbers that are equal to number.
#less_than finds numbers that are less than number.
#less_than_or_equal finds numbers that are less than or equal to number.
#greater_than finds numbers that are greater than number.
#greater_than_or_equal finds numbers that are greater than or equal to number.
search_backwards should be true if you want the search to be done backwards.
test_only_current should be true if you want to only search the current record.
Ex:
To search the database my_base for the number 123 in all fields type this:
{database my_base}:goto_first_record
f := {database my_base}:find_number({database my_base}:fields, 123, #equal, false, false)
if f <> false then
	{database my_base}:display_current_record
else
	{sound}:beep
end if
#end_method

#begin_method
get_field(field) 
Returns the value of field in the current record.
Ex:
{database my_base}:get_field(#name)
returns something like "Jake"
#end_method

#begin_method
goto_first_record 
Makes the first record in the database the current record.
Returns self.
Also see goto_first_record_and_display.
#end_method

#begin_method
goto_first_record_and_display 
Makes the first record in the database the current record and updates the controllers that are connected to the fields in the database.
Returns self.
Also see goto_first_record.
#end_method

#begin_method
goto_last_record 
Makes the last record in the database the current record.
Returns self.
Also see goto_last_record_and_display.
#end_method

#begin_method
goto_last_record_and_display 
Makes the last record in the database the current record and updates the controllers that are connected to the fields in the database.
Returns self.
Also see goto_last_record.
#end_method

#begin_method
goto_next_record 
Makes the next record in the database the current record.
Returns self.
Also see goto_next_record_and_display.
#end_method

#begin_method
goto_next_record_and_display 
Makes the next record in the database the current record and updates the controllers that are connected to the fields in the database.
Returns self.
Also see goto_next_record.
#end_method

#begin_method
goto_previous_record 
Makes the previous record in the database the current record.
Returns self.
Also see goto_previous_record_and_display.
#end_method

#begin_method
goto_previous_record_and_display 
Makes the previous record in the database the current record and updates the controllers that are connected to the fields in the database.
Returns self.
Also see goto_previous_record.
#end_method

#begin_method
has_backing_store 
Returns true if the database file exists on the hard disk and is not locked by another user. Otherwise the method returns false. 
Note: You cannot use the database if it has no backing store.
#end_method

#begin_method
import(file, field_delimiter, record_delimiter) 
Imports the contents of the text-file file to the database.
field_delimiter is the character that delimits fields in the text-file.
record_delimiter is the character that delimits records in the text-file.
Returns self.
Ex:
Assume the database {database my_base} has three fields: name, phone and birthdate.
If a text-file "my_data" looks something like this:

Steve	234 5656	2 Oct
Mike	123 3243	8 Nov
Lucy	873 1293	23 Jan

it can be imported into the database:
{database my_base}:import("my_data", \tab, \nl)
#end_method

#begin_method
input_control_for(field) 
Returns the input control for field. If the field does not have an input control the method returns nil.
#end_method

#begin_method
load_and_add_current_record 
Sets the values of the current record to the values of the connected input controllers and adds the current record to the database.
Returns self.
Note: This is equivalent to a load_current_record message followed by an add_current_record message.
Also see load_and_update_current_record.
#end_method

#begin_method
load_and_update_current_record 
Sets the values of the current record to the values of the connected input controllers and updates the current record of the database.
Returns self.
Note: This is equivalent to a load_current_record message followed by an update_current_record message.
Also see load_and_add_current_record.
#end_method

#begin_method
load_current_record 
Sets the values of the current record to the values of the connected input controllers.
Returns self.
Also see load_and_add_current_record and load_and_update_current_record.
#end_method

#begin_method
max_field(field) 
Returns the maximum of all the values of field in the database. The field must be of the type integer or float. Otherwise the method returns 0.
#end_method

#begin_method
min_field(field) 
Returns the minimum of all the values of field in the database. The field must be of the type integer or float. Otherwise the method returns 0.
#end_method

#begin_method
open_manager 
Opens the Database Manager window.
Returns self.
Also see close_manager.
#end_method

#begin_method
output_control_for(field) 
Returns the output control for field. If the field does not have an output control the method returns nil.
#end_method

#begin_method
remove_current_record 
Removes the current record from the database.
Returns self.
#end_method

#begin_method
search(fields, pattern, search_type, ignore_case, allow_regular_expr, search_backwards, test_only_current) 
Searches the database for a pattern. Only the fields specified by the collection fields are searched.
If a text is found that matches the pattern, the method returns the name of the field that included the text. The current record will be set to the record where the text was found. If there is no text in the database that matches the method returns false.
The symbol search_type determines the type of the search:
#within means that pattern should match any part of a field.
#prefix means that pattern should match the beginning of a word in a field.
#exactly means that pattern should match a field exactly.
#word means that pattern should match a word in the field.
ignore_case should be true if you want to ignore case in the search. (I.e. uppercase and lowercase characters are treated as equal).
allow_regular_expr should be true if you want the search pattern to be a regular expression. If allow_regular_expr is false, pattern is treated as a string.
search_backwards should be true if you want the search to be done backwards.
test_only_current should be true if you want to only search the current record.
Ex:
To search the database my_base for the text "hello" in all fields type this:
{database my_base}:goto_first_record
f := {database my_base}:search({database my_base}:fields, "hello", #within, true, false, false, false)
if f <> false then
	{database my_base}:display_current_record
else
	{sound}:beep
end if
#end_method

#begin_method
set_field(field, value) 
Sets the value of field to value in the current record.
Returns self.
#end_method

#begin_method
set_input_control_for(field, object) 
Sets the input control for field to object.
Returns self.
#end_method

#begin_method
set_output_control_for(field, object) 
Sets the output control for field to object.
Returns self.
#end_method

#begin_method
size 
Returns the number of records in the database.
#end_method

#begin_method
sort(fields) 
Sorts the database on the fields in the collection fields.
Returns self.
Ex:
{database my_database}:sort([#name #phone])
#end_method

#begin_method
sort_decreasing(fields, boolean) 
If boolean is true the fields in the collection fields will sort in decreasing order when the database receives a sort message. 
If boolean is false the fields will sort in increasing order.
Returns self.
Ex:
{database my_database}:sort_decreasing([#name #phone], true)
will make the fields name and phone sort in decreasing order.
#end_method

#begin_method
sum_field(field) 
Returns the sum of all the values of field in the database. The field must be of the type integer or float. Otherwise the method returns 0.
#end_method

#begin_method
update_current_record 
Updates the current record of the database. This message should be sent to the database after one or more set_field(field, value) messages have been used to set the values of the fields in the current record.
Returns self.
Also see add_current_record.
#end_method

#begin_method
update_manager 
Updates the Database Manager window to show the current status of the database.
Returns self.
#end_method

Class Methods 

#begin_class_method
new 
You can only create databases in edit-mode.
Ex:
{database}:new
raises an exception
Exception:
New databases can only be created in Edit Mode!
#end_class_method